<!DOCTYPE doctype PUBLIC "-//W3C//DTD HTML 4.0 Frameset//EN">

<HTML>
  <HEAD>
    <META name="generator" content=
    "HTML Tidy for Java (vers. 2009-12-01), see jtidy.sourceforge.net">

    <TITLE>Source Files</TITLE>
    <META http-equiv="content-type" content="text/html; charset=windows-1252">
    <LINK rel="stylesheet" type="text/css" href="help/shared/DefaultStyle.css">
  </HEAD>

  <BODY>
    <H1><A name="Source_Files_Table_Plugin"></A>Source Files Table Plugin</H1>

    <P>This plugin shows the source file information (described <A href=
    "#Source_File_Information">below</A>) associated with the current program and allows the user
    to manage source file path <A href="#Source_Path_Transformations">transforms</A>.</P>

    <H2><A name="Source_Files_Table"></A>Source Files Table</H2>

    <BLOCKQUOTE>
      <P>Each row in this table corresponds to a Source File added to the program's source file
      manager. The columns show the source file, path, transformed path, and number of source map
      entries for a source file. If the <I>Transformed Path</I> column is empty for a given source
      file, then no transformation applies to that file. Note that there are optional columns,
      hidden by default, to show the SourceFileIdType and identifier of each source file.</P>

      <H3><A name="Reload_Source_Files_Model"></A>Reload Model</H3>

      <P>This action reloads the Source File Table. Note that this can be an expensive operation
      since the number of source map entries must be computed for each source file. For this
      reason, the action is only enabled after program events which might change the data shown in
      the table.</P>

      <H3><A name="Show_Source_Map_Entries"></A>Show Source Map Entries</H3>

      <P>This action brings up a table which displays all of the source map entries for the
      selected source file.</P>

      <H3><A name="View_Source_File"></A>View Source Files</H3>

      <P>This action opens a source file (at line 1) in the configured viewer. Options for
      configuring the viewer are described <A href=
      "#Source_Files_Table_Plugin_Options">below</A>.</P>

      <H3><A name="Transform_File"></A>Transform File</H3>

      <P>This action allows you to create a file transform for the selected source file.</P>

      <H3><A name="Transform_Directory"></A>Transform Directory</H3>

      <P>This action allows you to create a directory transform whose source is a user-selected
      parent directory of the corresponding source file.</P>
    </BLOCKQUOTE>

    <H2><A name="Transforms_Table"></A>Transforms Table</H2>

    <BLOCKQUOTE>
      <P>This table shows all of the source file transformations defined for a program.</P>

      <H3><A name="Remove_Transform"></A>Remove Transform</H3>

      <P>This action removes the selected transform from the list of transforms.</P>

      <H3><A name="Edit_Transform"></A>Edit Transform</H3>

      <P>This action allows you to change the destination of a transform (but not the source).</P>
    </BLOCKQUOTE>

    <H2><A name="Source_Files_Table_Plugin_Actions"></A>Listing Actions</H2>

    <BLOCKQUOTE>
      <H3><A name="View_Source"></A>View Source</H3>

      <P>This Listing action is enabled if there is source map information for an address. It will
      open the corresponding source file at the appropriate line in a source code viewer (currently
      Eclipse and VS Code are supported). Options for configuring the viewer are described <A href=
      "#Source_Files_Table_Plugin_Options">below</A>. If there are multiple source map entries
      defined for an address, the user will be prompted to select which one to send to the viewer.
      Performing this action on a particular line of the Source Map Listing field will open the
      corresponding file in the viewer even if there are multiple entries defined at the current
      address.</P>
    </BLOCKQUOTE>

    <H2><A name="Source_Files_Table_Plugin_Options"></A>Plugin Options</H2>

    <P>These options can be changed from the Code Browser via Edit-&gt;-Tool Options-&gt;Source
    Files and Transforms.</P>

    <BLOCKQUOTE>
      <H3><A name="Use_Existing_As_Default"></A>Use Existing As Default</H3>

      <P>If enabled, the SourcePathTransformer will just return a SourceFile's path if no transform
      applies to the file.</P>

      <H3><A name="Viewer_for_Source_Files"></A>Viewer for Source Files</H3>

      <P>Selects the viewer to use for source files. The supported viewers are Eclipse and Visual
      Studio Code. Your viewer of choice must be configured via the appropriate option in the
      Front-End tool (aka Ghidra Project Window).</P>
    </BLOCKQUOTE>

    <H1><A name="Source_File_Information"></A>Source File Information</H1>

    <P>Ghidra can store information about the source files for a program, including their locations
    in the build environment and the correspondence between lines of source code and addresses in a
    program. A common source of this information is debug data, such as DWARF or PDB.</P>

    <P>A major use case of this information is to synchronize Ghidra with an IDE, such as
    Eclipse.</P>

    <H2>Source Files</H2>

    <P>A source file record in Ghidra consists of three pieces of information:</P>

    <BLOCKQUOTE>
      <OL>
        <LI>A path, which must be an absolute, normalized path using forward slashes. E.g.,
        "/usr/src/main/file.c", "/C:/Users/Ghidra/sourceFile.cc".</LI>

        <LI>A <I>SourceFileIdType</I>, which can be NONE, UNKNOWN, TIMESTAMP_64, MD5, SHA1, SHA256,
        or SHA512.</LI>

        <LI>An identifier, which is the value of the identifier as a byte array.</LI>
      </OL>
    </BLOCKQUOTE>

    <H2>Source Map Entries</H2>

    <P>A <I>Source Map Entry</I> associates a source file and a line number to an address or
    address range in a program. It consists of:</P>

    <BLOCKQUOTE>
      <OL>
        <LI>A source file.</LI>

        <LI>A line number.</LI>

        <LI>A base address.</LI>

        <LI>A length. If the length is non-zero, the entry defines an address range, otherwise it
        defines an address.</LI>
      </OL>
    </BLOCKQUOTE><BR>
     <BR>
     

    <P>Source map entries are constrained as follows:</P>

    <BLOCKQUOTE>
      <UL>
        <LI>An address in a program may not have duplicate (same source file, line number, base
        address, and length) source file entries.</LI>

        <LI>Given two source map entries with non-zero lengths, their associated address ranges
        must be either identical or distinct (i.e., no partial overlaps). Multiple source maps
        entries based at the same address are allowed as long as they obey this restriction. Length
        zero entries may occur anywhere, including within ranges corresponding to entries of
        non-zero lengths.</LI>
      </UL>
    </BLOCKQUOTE><BR>
     <BR>
     

    <H2>Source File Manager</H2>

    <P>Source files and source map entries are managed by a program's source file manager. A source
    file must be added to a program before it can used in a source map entry. The DWARF, PDB, and
    Go analyzers add source files and source map entries to a program by default. There are no GUI
    actions to add source files or source map entries to a program, but such information can be
    added to a program via a Ghidra Script. There are example scripts in the "SourceMapping" script
    category.</P>

    <BLOCKQUOTE>
      <P><IMG src="help/shared/note.png" alt="Note" border="0">Note that adding source files,
      removing source files, or changing the source map requires an exclusive checkout if the
      program is in a shared Ghidra repository. Reading the source file list or source map does not
      require an exclusive checkout.</P>
      <BR>
    </BLOCKQUOTE><BR>
     <BR>
     

    <H2><A name="Source_Path_Transformations"></A>Source Path Transformations</H2>

    <P>Source file path information can be sent to an external tool, such as an IDE. However, there
    is no guarantee that a path recorded for a source file exists on the machine running Ghidra.
    For instance, you could use Ghidra running under Linux to analyze a Windows program with source
    file information. An additional complication is that the program may be in a shared Ghidra
    repository where users have different operating systems or local file systems. We solve this
    issue by allowing users to modify source file paths. The modifications are stored locally for
    each user and are not checked in to a shared repository.</P>

    <P>A note on terminology: to avoid overuse of the word "map", we use "map" when discussing the
    association of a source file and a line number to an address and length in a program (the
    "source file map"). We use the word "transform" when discussing user-determined modifications
    of a source file's path.</P>

    <P>There are two type of source path transforms:</P>

    <BLOCKQUOTE>
      <OL>
        <LI><I>File Transforms</I>, which entirely replace a source file's path with another file
        path.</LI>

        <LI><I>Directory Transforms</I>, which replace a parent directory of a source file's path
        with another directory. For example, the directory transform "/src/ -&gt;
        "/usr/test/files/" would transform the path "/src/dir1/file.c" to
        "/usr/test/files/dir1/file.c".</LI>
      </OL>
    </BLOCKQUOTE><BR>
     <BR>
     

    <P>Given a source file, the transformed path is determined as follows. If there is a file
    transform for that particular file, the file transform is applied. Otherwise, the most specific
    directory transform (i.e., the one replacing the longest initial segment of the path) is
    applied. If no transform is applied, the user may opt to use the untransformed path.</P>

    <P>Source file path transformations are managed using a <I>SourcePathTransformer</I>. Path
    transformations can be managed using the actions on the <A href="#Source_Files_Table">Source
    Files Table</A>. In a script, you can get the path transformer for a program via the static
    method <I>UserDataPathTransformer.getPathTransformer(Program)</I>. Note that modifications to
    the path transformer are not affected by undo or redo actions in Ghidra.</P>

    <P class="relatedtopic">Related Topics:</P>

    <UL>
      <LI><A href="help/topics/CodeBrowserPlugin/CodeBrowserOptions.htm#Source_Map_Field">Source
      Map Field</A></LI>

      <LI><A href="help/topics/EclipseIntegration/EclipseIntegration.htm">Eclipse
      Integration</A></LI>

      <LI><A href="help/topics/VSCodeIntegration/VSCodeIntegration.htm">Visual Studio Code
      Integration</A></LI>
    </UL><BR>
     <BR>
     <BR>
     <BR>
     <BR>
     <BR>
     <BR>
     <BR>
  </BODY>
</HTML>
